.TH std::barrier 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::barrier \- std::barrier

.SH Synopsis
   Defined in header <barrier>
   template< class CompletionFunction = /* see below */ >  \fI(since C++20)\fP
   class barrier;

   The class template std::barrier provides a thread-coordination mechanism that blocks
   a group of threads of known size until all threads in that group have reached the
   barrier. Unlike std::latch, barriers are reusable: once a group of arriving threads
   are unblocked, the barrier can be reused. Unlike std::latch, barriers execute a
   possibly empty callable before unblocking threads.

   A barrier object's lifetime consists of one or more phases. Each phase defines a
   phase synchronization point where waiting threads block. Threads can arrive at the
   barrier, but defer waiting on the phase synchronization point by calling arrive.
   Such threads can later block on the phase synchronization point by calling wait.

   A barrier phase consists of the following steps:

    1. The expected count is decremented by each call to arrive or arrive_and_drop.
    2. When the expected count reaches zero, the phase completion step is run, meaning
       that the completion is invoked, and all threads blocked on the phase
       synchronization point are unblocked. The end of the completion step strongly
       happens-before all calls that were unblocked by the completion step return.
       Exactly once after the expected count reaches zero, a thread executes the
       completion step during its call to arrive, arrive_and_drop, or wait, except that
       it is implementation-defined whether the step executes if no thread calls wait.
    3. When the completion step finishes, the expected count is reset to the value
       specified at construction less the number of calls to arrive_and_drop since, and
       the next barrier phase begins.

   Concurrent invocations of the member functions of barrier, except for the
   destructor, do not introduce data races.

.SH Template parameters

   CompletionFunction               -               a function object type
   -
   CompletionFunction must meet the requirements of MoveConstructible and Destructible.
   std::is_nothrow_invocable_v<CompletionFunction&> must be true.

   The default template argument of CompletionFunction is an unspecified function
   object type that additionally meets the requirements of DefaultConstructible.
   Calling an lvalue of it with no arguments has no effects.

.SH Member objects

   Name                 Definition
                        A completion function object of type CompletionFunction which
   completion (private) is called on every phase completion step.
                        (exposition-only member object*)

.SH Member types

   Name          Definition
   arrival_token an unspecified object type meeting requirements of MoveConstructible,
                 MoveAssignable and Destructible

.SH Member functions

   constructor     constructs a barrier
                   \fI(public member function)\fP
   destructor      destroys the barrier
                   \fI(public member function)\fP
   operator=       barrier is not assignable
   [deleted]       \fI(public member function)\fP
   arrive          arrives at barrier and decrements the expected count
                   \fI(public member function)\fP
                   blocks at the phase synchronization point until its phase completion
   wait            step is run
                   \fI(public member function)\fP
                   arrives at barrier and decrements the expected count by one, then
   arrive_and_wait blocks until current phase completes
                   \fI(public member function)\fP
                   decrements both the initial expected count for subsequent phases and
   arrive_and_drop the expected count for current phase by one
                   \fI(public member function)\fP
.SH Constants
   max             the maximum value of expected count supported by the implementation
   \fB[static]\fP        \fI(public static member function)\fP

.SH Notes

   Feature-test macro  Value    Std                   Feature
                      201907L (C++20) std::barrier
   __cpp_lib_barrier  202302L (C++20) Relaxed guarantees for phase completion
                              (DR)

.SH Example


// Run this code

 #include <barrier>
 #include <iostream>
 #include <string>
 #include <syncstream>
 #include <thread>
 #include <vector>

 int main()
 {
     const auto workers = {"Anil", "Busara", "Carl"};

     auto on_completion = []() noexcept
     {
         // locking not needed here
         static auto phase =
             "... done\\n"
             "Cleaning up...\\n";
         std::cout << phase;
         phase = "... done\\n";
     };

     std::barrier sync_point(std::ssize(workers), on_completion);

     auto work = [&](std::string name)
     {
         std::string product = "  " + name + " worked\\n";
         std::osyncstream(std::cout) << product;  // ok, op<< call is atomic
         sync_point.arrive_and_wait();

         product = "  " + name + " cleaned\\n";
         std::osyncstream(std::cout) << product;
         sync_point.arrive_and_wait();
     };

     std::cout << "Starting...\\n";
     std::vector<std::jthread> threads;
     threads.reserve(std::size(workers));
     for (auto const& worker : workers)
         threads.emplace_back(work, worker);
 }

.SH Possible output:

 Starting...
   Anil worked
   Carl worked
   Busara worked
 ... done
 Cleaning up...
   Busara cleaned
   Carl cleaned
   Anil cleaned
 ... done

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

     DR    Applied to              Behavior as published               Correct behavior
   P2588R3 C++20      old phase completion guarantees might prevent    relaxed
                      hardware acceleration

.SH See also

   latch   single-use thread barrier
   (C++20) \fI(class)\fP
